home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 151-175 / scopedisk165 / filefind2 / filefind.doc < prev    next >
Text File  |  1995-03-19  |  17KB  |  361 lines
  1.  
  2.  
  3.  
  4.                               FileFind Amiga!
  5.                                 Version 2.0
  6.  
  7.                            Created by Ray Lambert
  8.  
  9.                          Copyright 1990 Ray Lambert
  10.  
  11.  
  12.  
  13.     FileFind is a utility which will search for files on AmigaDOS filing
  14. devices using filename wildcards.  The MS-DOS wildcards "*" and "?" can be
  15. used as well as the AmigaDOS wildcard "#" (in a slightly limited capacity),
  16. and a special character, "|", which allows multiple individual wildcard
  17. patterns to be used as one.  Specification of a drive/device is optional and
  18. if not supplied the currently logged drive is used.  An optional directory
  19. specifier may also be used which limits the search to the specified directory
  20. and all sub-directory levels under it.  Multiple arguments may be supplied to
  21. search on more than one drive for a particular file, or to search for
  22. multiple files on multiple devices.  Ctrl-C may be used to immediately
  23. terminate the search and return your CLI prompt to you.  Version 2.0 is pure
  24. and as such can be made resident.  It also actively supports Workbench,
  25. output redirection and background execution, as well as combinations of
  26. these.  Various options allow the user to control the depth of sub-directory
  27. searches and also to exclude certain sub-directories from the search.
  28.  
  29.  
  30.  
  31.                                Usage Template
  32.                                --------------
  33.  
  34.         [Run] FileFind [>output] [options] [DRIVE:][PATH/]PATTERN [...]
  35.  
  36.     where....
  37.  
  38.         [Run] is used to execute FileFind in the background (see Running 
  39.             FileFind In The Background, below)
  40.  
  41.         [>output] is used to to redirect FileFind's output to a disk file 
  42.             or another device such as a printer (see Redirecting FileFind's 
  43.             Output, below)
  44.       
  45.         [options] (see Options, below, for detailed descriptions)
  46.             +/-R  progress Report ON/OFF (default = ON)
  47.             +/-C  Case sensitivity ON/OFF (default = OFF)
  48.             +/-L  Log match directory ON/OFF (default = OFF)
  49.             +/-P  Path search ON/OFF (default = OFF)
  50.             =D#   set Depth limit (0 = infinite/default)
  51.             =X$   set eXclude path (null = no exclude/default)
  52.             =M#   set search Mode...
  53.                   (0 = non-stop (default); 1 = find one; 2 = query)
  54.  
  55.         [DRIVE:] is an optional drive/filing-system-device to search on
  56.  
  57.         [PATH/] is an optional path to begin searching in
  58.  
  59.         PATTERN is the filename to search for (see Pattern Matching, below)
  60.  
  61.         [...] indicates that multiple arguments may be specified optionally
  62.  
  63.  
  64.  
  65.                               The Command Line
  66.                               ----------------
  67.  
  68.     FileFind scans its command line sequentially, left to right.  It begins
  69. searching as soon as it finds a search pattern.  When a search is finished
  70. FileFind resumes scanning its command line from where it left off.  This
  71. allows multiple searches to be performed in one invocation of FileFind, with
  72. different options used for each search.  Although '[options]' and
  73. '[DRIVE:][PATH/]PATTERN' are shown in a specific order in the above template,
  74. in reality options and file patterns can be intermixed freely, as
  75. appropriate, on the command line.  Any option or file pattern which requires
  76. embedded space characters MUST be completely enclosed in double quotes.
  77.  
  78.  
  79.  
  80.                      Running FileFind In The Background
  81.                      ----------------------------------
  82.  
  83.     As with most programs, FileFind may be executed in the background using
  84. the AmigaDOS RUN command.  Unlike many programs however, FileFind knows when
  85. you do this and will take extra steps to cooperate.  Mainly, FileFind will
  86. open a console window and perform all of its operations in that window rather
  87. than the CLI or Shell window that it was executed from.  This allows the user
  88. to have FileFind doing its thing while the user's CLI remains free to do
  89. other things.  This may be desirable is some cases -- especially when
  90. searching on a large hard disk.  As fast as FileFind is (and it _is_ fast!)
  91. it can still take awhile to search a large volume.  Before FileFind closes
  92. its console window, it will wait for the user to press RETURN, thereby
  93. allowing the user time to read its final messages.
  94.  
  95.  
  96.  
  97.                         Redirecting FileFind's Output
  98.                         -----------------------------
  99.  
  100.     As with most programs, FileFind's output may be redirected to a device
  101. other than the console that it was executed from (normally a disk file or the
  102. printer).  Unlike many programs however, FileFind knows when you do this and
  103. will take extra steps to cooperate -- FileFind will strip all ANSI control
  104. sequences from its output.  
  105.     Output redirection is a normal function of AmigaDOS.  It is accomplished
  106. by placing the name of the output device (or filename) directly following the
  107. program name and seperated by at least one space character.  The output
  108. device name must be prefixed with a right angle bracket character.
  109. Optionally, two right angle brackets may be used to indicate an append
  110. operation (if the disk file already exists, the new data will be appended to
  111. the end of it, as opposed to erasing the file's former contents -- however if
  112. the file does not exist AmigaDOS will issue an error).  If FileFind's output
  113. is redirected to a non-interactive device (such as a disk file or the printer
  114. -- this is virtually always the case) then 'query mode' (see the Options
  115. section, below) is implicitly disabled.  Also, progress reporting is also
  116. implicitly disabled by output redirection.
  117.  
  118.  
  119.  
  120.         Background Execution And Output Redirection At The Same Time
  121.         ------------------------------------------------------------
  122.  
  123.     If FileFind is executed in the background _and_ its output is redirected
  124. at the same time it will operate slightly differently.  In this case, the
  125. output redirection will take place as descibed in the previous section, and
  126. FileFind will still open a console window, however it will not use the
  127. console window in the same manner as described in the section entitled
  128. "Running FileFind In The Background".  Rather, FileFind will open a small
  129. window and simply display its title in that window.  The user knows that the
  130. search operation is complete when the title window goes away.
  131.  
  132.  
  133.  
  134.                        Running FileFind From Workbench
  135.                        -------------------------------
  136.  
  137.     FileFind can be run from Workbench by simply double-clicking on its icon.
  138. When run from Workbench, FileFind opens a console window much as it does when
  139. it is run in the background from the CLI or Shell.  Except that it will
  140. prompt the user to enter a command.  The syntax for a Workbench command line
  141. is the same as that for a CLI command line (as described above in the
  142. template) except that the RUN command is not allowed and nor is the program
  143. name itself (FileFind).  Output redirection _IS_ supported on FileFind's
  144. Workbench command line, including append mode using double right angle
  145. brackets!  If output redirection is used on the Workbench command line, the
  146. redirection command MUST appear first and it is suggested that a full path
  147. name be used as Workbench's idea of a current directory is a bit fuzzy to say
  148. the least -- if you do not use a full path name you may end-up using FileFind
  149. again just to find your redirection file [grin]!  
  150.  
  151.  
  152.  
  153.                                    Options
  154.                                    -------
  155.  
  156.     FileFind's command line options must be prefixed with either a plus (+)
  157. sign, a minus (-) sign, or an equals (=) sign.  Plus and minus signs are used
  158. on options which can be toggled ON and OFF (plus means ON and minus means
  159. OFF), while an equals sign is used on options which define a specific value.
  160. After the prefix is a letter that indicates which option is being defined
  161. (the case of the letter is not significant).  Following options that are
  162. prefixed with an equals sign is an alpha-numeric value with no intervening
  163. spaces.  A detailed desciption of each option follows:
  164.  
  165.  
  166.     Progress Report (+R or -R -- ON by default)
  167.  
  168.         When this option is on, FileFind will display the full name of
  169.     every sub-directory it searches in.  If ON, this option will slow
  170.     FileFind down a bit, so for maximum search speed it is neccessary to
  171.     turn this option OFF.  When a sub-directory name is displayed it
  172.     overwrites any previous progress report.  If a sub-directory name is
  173.     too long to print in the console window without causing a scroll to
  174.     occur, FileFind will truncate the name on the left, allowing the actual
  175.     sub-directory name to be always visible.  When a sub-directory name
  176.     gets truncated, a double arrow character («) will be prefixed to the
  177.     truncated name to indicate that the name was truncated.
  178.  
  179.  
  180.     Case Sensitivity (+C or -C -- OFF by default)
  181.  
  182.         When ON, this option will force all wildcard matches
  183.     (including sub-directory excludes -- see below) to be case-sensitive.
  184.  
  185.  
  186.     Log Last Match Directory (+L or -L -- OFF by default)
  187.  
  188.         When ON, this option will cause FildFind to change the current
  189.     working directory to the directory in which the last match was found.
  190.     Note that this option is explicitly disabled when FileFind is run from
  191.     Workbench or run in the background.
  192.  
  193.  
  194.     Path Search (+P or -P -- OFF by default)
  195.  
  196.         When this option is on, FileFind will search all the
  197.     directories in your path (see the AmigaDOS PATH command), rather than a
  198.     branch of the directory tree.  FileFind will only search in mounted
  199.     path locations, and will always look in the current directory and the
  200.     'C:' directory.  FileFind will not look in any sub-directories which
  201.     branch off directories defined in your path, therefore, the
  202.     'Sub-directory Search Depth Limit' and the 'Sub-directory Exclude Path'
  203.     options (see below) have no effect when this option is ON.  When run
  204.     from Workbench, FileFind will normally search only the current
  205.     directory and the 'C:' directory, because programs do not normally
  206.     inherit a path definition from Workbench (note that this may change
  207.     under Workbench 2.0).
  208.  
  209.  
  210.     Set Sub-directory Search Depth Limit (=D# -- 0 (infinite) by default)
  211.  
  212.         This option allows the user to place a limit on how many
  213.     sub-directories deep FileFind will search into the directory tree.
  214.     Replace the '#' character with a numeric (decimal) value to define a
  215.     limit or to remove a previously defined limit.  A value of zero
  216.     indicates infinite depth.  Any other value will place a limit into
  217.     effect.  The first directory that FileFind looks in is considered the
  218.     'root' directory, and sub-directories of that 'root' are considered one
  219.     level deep.  FileFind will not search at or deeper than the defined
  220.     limit.  Therefore, a level of one will cause only the 'root' directory
  221.     to be searched in.
  222.  
  223.  
  224.     Set Sub-directory Exclude Path (=X$ -- none by default)
  225.  
  226.         This option allows the user to instruct FileFind to ignore
  227.     specific directories that it encounters during its search.  Replace the
  228.     '$' character with a pattern string which matches the directory(s)
  229.     which should be excluded.  If nothing appears after the 'X' character
  230.     any previously defined exclude path will be cleared, leaving no exclude
  231.     path active.  Each exclude path definition on a single command line
  232.     replaces all previous definitions -- multiple definitions are not
  233.     additive.  When FileFind encounters a sub-directory during its search,
  234.     normally it enters that sub-directory to perform a search in it.
  235.     However if that sub-directory name matches the active exclude path,
  236.     FileFind will simply ignore it and continue searching the directory it
  237.     is in.  Note that when FileFind excludes a sub-directory in this manner
  238.     it also effectively excludes all sub-directories which are lower on the
  239.     same branch.  Note also that FileFind performs a compare only on the
  240.     sub-directory name itself -- it does not use the full path name of the
  241.     sub-directory.  See the section on patterns (below) for a
  242.     desciption of what wildcards can be used in an exclude path.
  243.  
  244.  
  245.     Set Search Mode (=M# -- 0 (non-stop) by default)
  246.  
  247.         This option allows the user to control FileFind's action upon
  248.     finding a matching file.  Three modes are currently offered.  One of
  249.     these three modes is selected by replacing the '#' character with one
  250.     of three digits representing the three modes:  '0', '1' or '2'.  Mode
  251.     '0', also called 'non-stop' mode, is the default.  In this mode
  252.     FileFind continues searching after finding a match until all places to
  253.     search in have been exhausted.  When in mode '1' (also called 'find
  254.     one' mode) FileFind will stop searching after finding the first match.
  255.     In mode '2' (also called 'query mode') FileFind will pause and prompt
  256.     the user for what to do next.  FileFind will ask 'Continue searching?',
  257.     and the user must give one of the following answers:  'Yes', 'No' or
  258.     'Abort' (note that the user need only type the first letter of each
  259.     response).  'Yes' will cause FileFind to resume searching -- it will
  260.     pause again with the next match it finds.  'No' will cause FileFind to
  261.     stop the search right away.  'Abort' will do the same as 'No' except
  262.     that 'No' will still allow the directory to be logged if the +L option
  263.     is active while 'Abort' will not.  
  264.         Note that if multiple search patterns where given on the
  265.     command line, and FileFind has not yet reached the last one, 
  266.     FileFind will go on to the next search pattern when it stops searching
  267.     on the surrent one, rather than simply exiting -- this is true for
  268.     both the 'No' and 'Abort' responses in 'query mode', and it is also
  269.     for 'find one mode'.
  270.         Note that this mode is implicitly disabled if FileFind's output
  271.     has been redirected to a non-interactive device (such as a disk file
  272.     or the printer).
  273.  
  274.  
  275.  
  276.  
  277.                            Pattern Matching
  278.                            ----------------
  279.  
  280.     FileFind uses pattern matching both to locate files and to find
  281. sub-directories to exclude in conjunction with its Sub-directory
  282. Exclude option.  'Pattern Strings' are used to perform matching.
  283. Pattern strings consist of literal characters as well as 'wildcards'
  284. which match any character(s).  FileFind recognizes the following
  285. wildcard characters:
  286.  
  287.         ?   - matches one of any character.
  288.         #x  - matches one or more occurances of "x", which can be
  289.               any valid character.
  290.         *   - matches any number of any characters.
  291.         #?  - a special case of "#x" and "?" which works the same as "*".
  292.         |   - indicates the beginning of a new pattern string -- this
  293.               wildcard DOES NOT work in the same manner as it does in
  294.               AmigaDOS pattern matching -- rather, it is used to
  295.               concatenate multiple pattern strings to be matched in a 
  296.               parallel fashion -- think of it as meaning 'or'...
  297.               match 'this' _or_ 'this' _or_ 'this', etc.
  298.  
  299.  
  300.  
  301.  
  302.                             Some Usage examples:
  303.                             --------------------
  304.  
  305.  
  306.                  Search for all C source files on "DH0:"...
  307.  
  308.                               FileFind DH0:*.c
  309.  
  310.  
  311.         Search for all files with the word "disk" in them in "c:"...
  312.  
  313.                               FileFind c:*disk*
  314.  
  315.  
  316.     Search in the CLI path for all files with the word "disk" in them...
  317.  
  318.                             FileFind +p c:*disk*
  319.  
  320.  
  321.       Search for all Workbench icon files (.info) on "DH0:" and "DH1:".
  322.          Exclude all "fonts" directories on DH0: but not on DH1:...
  323.  
  324.                  FileFind =x*fonts* dh0:*.info =x dh1:*.info
  325.  
  326.  
  327.              Search for all ".c" and ".h" files on DH0: and SRC:
  328.              Exclude all "fonts" directories and use query mode
  329.  
  330.                FileFind =x*fonts* =m2 dh0:*.c|*.h src:*.c|*.h
  331.  
  332.  
  333.    Search for all ".info" files on DF0: and send the output to the printer
  334.            Also run FileFind in the background to free-up the CLI
  335.  
  336.                         Run FileFind >prt: df0:*.info
  337.  
  338.  
  339.  
  340.  
  341.                                  Legalities
  342.                                  ----------
  343.  
  344.     FileFind is FreeWare.  This means that I retain all rights to the program
  345. but give permission for it be distributed freely, so long so no charge is
  346. made for the program itself.  This document and notice should accompany any
  347. distribution of the program.  FileFind may not be sold commercially without
  348. permission from the author.
  349.  
  350.     If you have questions, complaints, suggestions, propositions, etc., you
  351. may contact me at the following places:
  352.  
  353. People Link:    Analog*Kid        (call often)
  354.  
  355. BIX:            AnalogKid         (call sparsely)
  356.     
  357. Home:           Ray Lambert
  358.                 PO Box 1253
  359.                 Westport, Massachusetts  02790
  360.                 Phone: (508) 677-9217
  361.